<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en"><head>
    <meta http-equiv="Content-type" content="text/html; charset=UTF-8">
    <meta http-equiv="Content-Language" content="en-us">
    <title>Django | Widgets | Django documentation</title>
    <meta name="ROBOTS" content="ALL">
    <meta http-equiv="imagetoolbar" content="no">
    <meta name="MSSmartTagsPreventParsing" content="true">
    <meta name="Copyright" content="Django Software Foundation">
    <meta name="keywords" content="Python, Django, framework, open-source">
    <meta name="description" content="Django is a high-level Python Web framework that encourages rapid development and clean, pragmatic design.">
    <link href="choice_files/base.css" rel="stylesheet" type="text/css" media="screen">
    <link href="choice_files/print.css" rel="stylesheet" type="text/css" media="print">
    
  
  <link rel="stylesheet" href="choice_files/docs.css" type="text/css">
  <link rel="stylesheet" href="choice_files/pygments.css" type="text/css">

  </head>
  <body id="documentation" class="default">
  <div id="container">
    <div id="header">
      <h1 id="logo"><a href="https://www.djangoproject.com/"><img src="choice_files/hdr_logo.gif" alt="Django"></a></h1>
      <ul id="nav-global">
        <li id="nav-homepage"><a href="https://www.djangoproject.com/">Home</a></li>
        <li id="nav-download"><a href="https://www.djangoproject.com/download/">Download</a></li>
        <li id="nav-documentation"><a href="https://docs.djangoproject.com/">Documentation</a></li>
        <li id="nav-weblog"><a href="https://www.djangoproject.com/weblog/">Weblog</a></li>
        <li id="nav-community"><a href="https://www.djangoproject.com/community/">Community</a></li>
        <li id="nav-code"><a href="https://code.djangoproject.com/">Code</a></li>
      </ul>
    </div>
    <!-- END Header -->
    <div id="billboard">
  <h2><a href="https://docs.djangoproject.com/en/dev/">Django documentation</a></h2>
</div>
    <div id="columnwrap">
      
		<div id="content-main">
		


  
  
  <ul id="doc-versions">
      
        
          <li class="other">
            <a href="https://docs.djangoproject.com/en/1.0/ref/forms/widgets/">1.0</a></li>
        
      
        
          <li class="other">
            <a href="https://docs.djangoproject.com/en/1.1/ref/forms/widgets/">1.1</a></li>
        
      
        
          <li class="other">
            <a href="https://docs.djangoproject.com/en/1.2/ref/forms/widgets/">1.2</a></li>
        
      
        
          <li class="other">
            <a href="https://docs.djangoproject.com/en/1.3/ref/forms/widgets/">1.3</a></li>
        
      
        
      
      <li class="current" title="This document is for Django's development version, which can be significantly different from previous releases. Click on the links on the left to see other versions.">
        <span>Documentation version:
          <strong>dev</strong>
        </span>
      </li>
  </ul>
  <div class="section" id="s-module-django.forms.widgets">
<span id="s-widgets"></span><span id="module-django.forms.widgets"></span><span id="widgets"></span><h1>Widgets<a class="headerlink" href="#module-django.forms.widgets" title="Permalink to this headline">¶</a></h1>
<p>A widget is Django’s representation of a HTML input element. The widget
handles the rendering of the HTML, and the extraction of data from a GET/POST
dictionary that corresponds to the widget.</p>
<div class="section" id="s-specifying-widgets">
<span id="specifying-widgets"></span><h2>Specifying widgets<a class="headerlink" href="#specifying-widgets" title="Permalink to this headline">¶</a></h2>
<p>Whenever you specify a field on a form, Django will use a default widget
that is appropriate to the type of data that is to be displayed. To find
which widget is used on which field, see the documentation about
<a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#built-in-fields"><em>Built-in Field classes</em></a>.</p>
<p>However, if you want to use a different widget for a field, you can
just use the <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.Field.widget" title="django.forms.Field.widget"><tt class="xref py py-attr docutils literal"><span class="pre">widget</span></tt></a> argument on the field definition. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">Textarea</span><span class="p">)</span>
</pre></div>
</div>
<p>This would specify a form with a comment that uses a larger <a class="reference internal" href="#django.forms.Textarea" title="django.forms.Textarea"><tt class="xref py py-class docutils literal"><span class="pre">Textarea</span></tt></a>
widget, rather than the default <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a> widget.</p>
</div>
<div class="section" id="s-setting-arguments-for-widgets">
<span id="setting-arguments-for-widgets"></span><h2>Setting arguments for widgets<a class="headerlink" href="#setting-arguments-for-widgets" title="Permalink to this headline">¶</a></h2>
<p>Many widgets have optional extra arguments; they can be set when defining the
widget on the field. In the following example, the
<tt class="xref py py-attr docutils literal"><span class="pre">years</span></tt> attribute is set for a
<a class="reference internal" href="#django.forms.extras.widgets.SelectDateWidget" title="django.forms.extras.widgets.SelectDateWidget"><tt class="xref py py-class docutils literal"><span class="pre">SelectDateWidget</span></tt></a>:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django.forms.fields</span> <span class="kn">import</span> <span class="n">DateField</span><span class="p">,</span> <span class="n">ChoiceField</span><span class="p">,</span> <span class="n">MultipleChoiceField</span>
<span class="kn">from</span> <span class="nn">django.forms.widgets</span> <span class="kn">import</span> <span class="n">RadioSelect</span><span class="p">,</span> <span class="n">CheckboxSelectMultiple</span>
<span class="kn">from</span> <span class="nn">django.forms.extras.widgets</span> <span class="kn">import</span> <span class="n">SelectDateWidget</span>

<span class="n">BIRTH_YEAR_CHOICES</span> <span class="o">=</span> <span class="p">(</span><span class="s">'1980'</span><span class="p">,</span> <span class="s">'1981'</span><span class="p">,</span> <span class="s">'1982'</span><span class="p">)</span>
<span class="n">GENDER_CHOICES</span> <span class="o">=</span> <span class="p">((</span><span class="s">'m'</span><span class="p">,</span> <span class="s">'Male'</span><span class="p">),</span> <span class="p">(</span><span class="s">'f'</span><span class="p">,</span> <span class="s">'Female'</span><span class="p">))</span>
<span class="n">FAVORITE_COLORS_CHOICES</span> <span class="o">=</span> <span class="p">((</span><span class="s">'blue'</span><span class="p">,</span> <span class="s">'Blue'</span><span class="p">),</span>
                            <span class="p">(</span><span class="s">'green'</span><span class="p">,</span> <span class="s">'Green'</span><span class="p">),</span>
                            <span class="p">(</span><span class="s">'black'</span><span class="p">,</span> <span class="s">'Black'</span><span class="p">))</span>

<span class="k">class</span> <span class="nc">SimpleForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">birth_year</span> <span class="o">=</span> <span class="n">DateField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">SelectDateWidget</span><span class="p">(</span><span class="n">years</span><span class="o">=</span><span class="n">BIRTH_YEAR_CHOICES</span><span class="p">))</span>
    <span class="n">gender</span> <span class="o">=</span> <span class="n">ChoiceField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">RadioSelect</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">GENDER_CHOICES</span><span class="p">)</span>
    <span class="n">favorite_colors</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">MultipleChoiceField</span><span class="p">(</span><span class="n">required</span><span class="o">=</span><span class="bp">False</span><span class="p">,</span>
        <span class="n">widget</span><span class="o">=</span><span class="n">CheckboxSelectMultiple</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">FAVORITE_COLORS_CHOICES</span><span class="p">)</span>
</pre></div>
</div>
<p>See the <a class="reference internal" href="#built-in-widgets"><em>Built-in widgets</em></a> for more information about which widgets
are available and which arguments they accept.</p>
</div>
<div class="section" id="s-widgets-inheriting-from-the-select-widget">
<span id="widgets-inheriting-from-the-select-widget"></span><h2>Widgets inheriting from the Select widget<a class="headerlink" href="#widgets-inheriting-from-the-select-widget" title="Permalink to this headline">¶</a></h2>
<p>Widgets inheriting from the <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a> widget deal with choices. They
present the user with a list of options to choose from. The different widgets
present this choice differently; the <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a> widget itself uses a
<tt class="docutils literal"><span class="pre">&lt;select&gt;</span></tt> HTML list representation, while <a class="reference internal" href="#django.forms.RadioSelect" title="django.forms.RadioSelect"><tt class="xref py py-class docutils literal"><span class="pre">RadioSelect</span></tt></a> uses radio
buttons.</p>
<p><a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a> widgets are used by default on <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.ChoiceField" title="django.forms.ChoiceField"><tt class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></tt></a> fields. The
choices displayed on the widget are inherited from the <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.ChoiceField" title="django.forms.ChoiceField"><tt class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></tt></a> and
changing <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.ChoiceField.choices" title="django.forms.ChoiceField.choices"><tt class="xref py py-attr docutils literal"><span class="pre">ChoiceField.choices</span></tt></a> will update <a class="reference internal" href="#django.forms.Select.choices" title="django.forms.Select.choices"><tt class="xref py py-attr docutils literal"><span class="pre">Select.choices</span></tt></a>. For
example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">CHOICES</span> <span class="o">=</span> <span class="p">((</span><span class="s">'1'</span><span class="p">,</span> <span class="s">'First'</span><span class="p">,),</span> <span class="p">(</span><span class="s">'2'</span><span class="p">,</span> <span class="s">'Second'</span><span class="p">,)))</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">ChoiceField</span><span class="p">(</span><span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">RadioSelect</span><span class="p">,</span> <span class="n">choices</span><span class="o">=</span><span class="n">CHOICES</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First'), ('2', 'Second')]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First'), ('2', 'Second')]</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span> <span class="o">=</span> <span class="p">()</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span><span class="o">.</span><span class="n">choices</span> <span class="o">=</span> <span class="p">((</span><span class="s">'1'</span><span class="p">,</span> <span class="s">'First and only'</span><span class="p">,),)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">choice_field</span><span class="o">.</span><span class="n">widget</span><span class="o">.</span><span class="n">choices</span>
<span class="go">[('1', 'First and only')]</span>
</pre></div>
</div>
<p>Widgets which offer a <a class="reference internal" href="#django.forms.Select.choices" title="django.forms.Select.choices"><tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt></a> attribute can however be used
with fields which are not based on choice -- such as a <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.CharField" title="django.forms.CharField"><tt class="xref py py-class docutils literal"><span class="pre">CharField</span></tt></a> --
but it is recommended to use a <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.ChoiceField" title="django.forms.ChoiceField"><tt class="xref py py-class docutils literal"><span class="pre">ChoiceField</span></tt></a>-based field when the
choices are inherent to the model and not just the representational widget.</p>
</div>
<div class="section" id="s-customizing-widget-instances">
<span id="customizing-widget-instances"></span><h2>Customizing widget instances<a class="headerlink" href="#customizing-widget-instances" title="Permalink to this headline">¶</a></h2>
<p>When Django renders a widget as HTML, it only renders the bare minimum
HTML - Django doesn't add a class definition, or any other widget-specific
attributes. This means that all <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a> widgets will appear the same
on your Web page.</p>
<p>If you want to make one widget look different to another, you need to
specify additional attributes for each widget. When you specify a
widget, you can provide a list of attributes that will be added to the
rendered HTML for the widget.</p>
<p>For example, take the following simple form:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="kn">from</span> <span class="nn">django</span> <span class="kn">import</span> <span class="n">forms</span>

<span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">()</span>
</pre></div>
</div>
<p>This form will include three default <a class="reference internal" href="#django.forms.TextInput" title="django.forms.TextInput"><tt class="xref py py-class docutils literal"><span class="pre">TextInput</span></tt></a> widgets, with default
rendering -- no CSS class, no extra attributes. This means that the input boxes
provided for each widget will be rendered exactly the same:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" /&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
<p>On a real Web page, you probably don't want every widget to look the same. You
might want a larger input element for the comment, and you might want the
'name' widget to have some special CSS class. To do this, you use the
<a class="reference internal" href="#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><tt class="xref py py-attr docutils literal"><span class="pre">Widget.attrs</span></tt></a> argument when creating the widget:</p>
<p>For example:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">CommentForm</span><span class="p">(</span><span class="n">forms</span><span class="o">.</span><span class="n">Form</span><span class="p">):</span>
    <span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span>
                <span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">'class'</span><span class="p">:</span><span class="s">'special'</span><span class="p">}))</span>
    <span class="n">url</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">URLField</span><span class="p">()</span>
    <span class="n">comment</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">CharField</span><span class="p">(</span>
               <span class="n">widget</span><span class="o">=</span><span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">'size'</span><span class="p">:</span><span class="s">'40'</span><span class="p">}))</span>
</pre></div>
</div>
<p>Django will then include the extra attributes in the rendered output:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">f</span> <span class="o">=</span> <span class="n">CommentForm</span><span class="p">(</span><span class="n">auto_id</span><span class="o">=</span><span class="bp">False</span><span class="p">)</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">f</span><span class="o">.</span><span class="n">as_table</span><span class="p">()</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Name:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="name" class="special"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Url:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="url"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
<span class="go">&lt;tr&gt;&lt;th&gt;Comment:&lt;/th&gt;&lt;td&gt;&lt;input type="text" name="comment" size="40"/&gt;&lt;/td&gt;&lt;/tr&gt;</span>
</pre></div>
</div>
</div>
<div class="section" id="s-built-in-widgets">
<span id="s-id1"></span><span id="built-in-widgets"></span><span id="id1"></span><h2>Built-in widgets<a class="headerlink" href="#built-in-widgets" title="Permalink to this headline">¶</a></h2>
<p>Django provides a representation of all the basic HTML widgets, plus some
commonly used groups of widgets:</p>
<div class="section" id="s-widget">
<span id="widget"></span><h3><tt class="docutils literal"><span class="pre">Widget</span></tt><a class="headerlink" href="#widget" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.Widget">
<em class="property">class </em><tt class="descname">Widget</tt><a class="headerlink" href="#django.forms.Widget" title="Permalink to this definition">¶</a></dt>
<dd><p>This abstract class cannot be rendered, but provides the basic attribute <a class="reference internal" href="#django.forms.Widget.attrs" title="django.forms.Widget.attrs"><tt class="xref py py-attr docutils literal"><span class="pre">attrs</span></tt></a>.</p>
<dl class="attribute">
<dt id="django.forms.Widget.attrs">
<tt class="descname">attrs</tt><a class="headerlink" href="#django.forms.Widget.attrs" title="Permalink to this definition">¶</a></dt>
<dd><p>A dictionary containing HTML attributes to be set on the rendered widget.</p>
<div class="highlight-python"><div class="highlight"><pre><span class="gp">&gt;&gt;&gt; </span><span class="n">name</span> <span class="o">=</span> <span class="n">forms</span><span class="o">.</span><span class="n">TextInput</span><span class="p">(</span><span class="n">attrs</span><span class="o">=</span><span class="p">{</span><span class="s">'size'</span><span class="p">:</span> <span class="mi">10</span><span class="p">,</span> <span class="s">'title'</span><span class="p">:</span> <span class="s">'Your name'</span><span class="p">,})</span>
<span class="gp">&gt;&gt;&gt; </span><span class="n">name</span><span class="o">.</span><span class="n">render</span><span class="p">(</span><span class="s">'name'</span><span class="p">,</span> <span class="s">'A name'</span><span class="p">)</span>
<span class="go">u'&lt;input title="Your name" type="text" name="name" value="A name" size="10" /&gt;'</span>
</pre></div>
</div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-textinput">
<span id="textinput"></span><h3><tt class="docutils literal"><span class="pre">TextInput</span></tt><a class="headerlink" href="#textinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.TextInput">
<em class="property">class </em><tt class="descname">TextInput</tt><a class="headerlink" href="#django.forms.TextInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Text input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></p>
</dd></dl>

</div>
<div class="section" id="s-passwordinput">
<span id="passwordinput"></span><h3><tt class="docutils literal"><span class="pre">PasswordInput</span></tt><a class="headerlink" href="#passwordinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.PasswordInput">
<em class="property">class </em><tt class="descname">PasswordInput</tt><a class="headerlink" href="#django.forms.PasswordInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Password input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='password'</span> <span class="pre">...&gt;</span></tt></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.PasswordInput.render_value">
<tt class="descname">render_value</tt><a class="headerlink" href="#django.forms.PasswordInput.render_value" title="Permalink to this definition">¶</a></dt>
<dd><p>Determines whether the widget will have a value filled in when the
form is re-displayed after a validation error (default is <tt class="xref docutils literal"><span class="pre">False</span></tt>).</p>
<div class="versionchanged">
<span class="title">Changed in Django 1.3:</span> The default value for
<a class="reference internal" href="#django.forms.PasswordInput.render_value" title="django.forms.PasswordInput.render_value"><tt class="xref py py-attr docutils literal"><span class="pre">render_value</span></tt></a> was
changed from <tt class="xref docutils literal"><span class="pre">True</span></tt> to <tt class="xref docutils literal"><span class="pre">False</span></tt></div>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-hiddeninput">
<span id="hiddeninput"></span><h3><tt class="docutils literal"><span class="pre">HiddenInput</span></tt><a class="headerlink" href="#hiddeninput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.HiddenInput">
<em class="property">class </em><tt class="descname">HiddenInput</tt><a class="headerlink" href="#django.forms.HiddenInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Hidden input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='hidden'</span> <span class="pre">...&gt;</span></tt></p>
</dd></dl>

</div>
<div class="section" id="s-multiplehiddeninput">
<span id="multiplehiddeninput"></span><h3><tt class="docutils literal"><span class="pre">MultipleHiddenInput</span></tt><a class="headerlink" href="#multiplehiddeninput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.MultipleHiddenInput">
<em class="property">class </em><tt class="descname">MultipleHiddenInput</tt><a class="headerlink" href="#django.forms.MultipleHiddenInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Multiple <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='hidden'</span> <span class="pre">...&gt;</span></tt> widgets.</p>
<p>A widget that handles multiple hidden widgets for fields that have a list
of values.</p>
<dl class="attribute">
<dt id="django.forms.MultipleHiddenInput.choices">
<tt class="descname">choices</tt><a class="headerlink" href="#django.forms.MultipleHiddenInput.choices" title="Permalink to this definition">¶</a></dt>
<dd><p>This attribute is optional when the field does not have a
<tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt> attribute. If it does, it will override anything
you set here when the attribute is updated on the <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.Field" title="django.forms.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a>.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-fileinput">
<span id="fileinput"></span><h3><tt class="docutils literal"><span class="pre">FileInput</span></tt><a class="headerlink" href="#fileinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.FileInput">
<em class="property">class </em><tt class="descname">FileInput</tt><a class="headerlink" href="#django.forms.FileInput" title="Permalink to this definition">¶</a></dt>
<dd><p>File upload input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='file'</span> <span class="pre">...&gt;</span></tt></p>
</dd></dl>

</div>
<div class="section" id="s-clearablefileinput">
<span id="clearablefileinput"></span><h3><tt class="docutils literal"><span class="pre">ClearableFileInput</span></tt><a class="headerlink" href="#clearablefileinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.ClearableFileInput">
<em class="property">class </em><tt class="descname">ClearableFileInput</tt><a class="headerlink" href="#django.forms.ClearableFileInput" title="Permalink to this definition">¶</a></dt>
<dd><div class="versionadded">
<span class="title">New in Django 1.3:</span> <a class="reference internal" href="https://docs.djangoproject.com/en/dev/releases/1.3/"><em>Please see the release notes</em></a></div>
<p>File upload input: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='file'</span> <span class="pre">...&gt;</span></tt>, with an additional checkbox
input to clear the field's value, if the field is not required and has
initial data.</p>
</dd></dl>

</div>
<div class="section" id="s-dateinput">
<span id="dateinput"></span><h3><tt class="docutils literal"><span class="pre">DateInput</span></tt><a class="headerlink" href="#dateinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.DateInput">
<em class="property">class </em><tt class="descname">DateInput</tt><a class="headerlink" href="#django.forms.DateInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Date input as a simple text box: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateInput.format">
<tt class="descname">format</tt><a class="headerlink" href="#django.forms.DateInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field's initial value will be displayed.</p>
</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">format</span></tt> argument is provided, the default format is the first
format found in <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DATE_INPUT_FORMATS"><tt class="xref std std-setting docutils literal"><span class="pre">DATE_INPUT_FORMATS</span></tt></a> and respects
<a class="reference internal" href="https://docs.djangoproject.com/en/dev/topics/i18n/formatting/#format-localization"><em>Format localization</em></a>.</p>
</dd></dl>

</div>
<div class="section" id="s-datetimeinput">
<span id="datetimeinput"></span><h3><tt class="docutils literal"><span class="pre">DateTimeInput</span></tt><a class="headerlink" href="#datetimeinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.DateTimeInput">
<em class="property">class </em><tt class="descname">DateTimeInput</tt><a class="headerlink" href="#django.forms.DateTimeInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Date/time input as a simple text box: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.DateTimeInput.format">
<tt class="descname">format</tt><a class="headerlink" href="#django.forms.DateTimeInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field's initial value will be displayed.</p>
</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">format</span></tt> argument is provided, the default format is the first
format found in <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-DATETIME_INPUT_FORMATS"><tt class="xref std std-setting docutils literal"><span class="pre">DATETIME_INPUT_FORMATS</span></tt></a> and respects
<a class="reference internal" href="https://docs.djangoproject.com/en/dev/topics/i18n/formatting/#format-localization"><em>Format localization</em></a>.</p>
</dd></dl>

</div>
<div class="section" id="s-timeinput">
<span id="timeinput"></span><h3><tt class="docutils literal"><span class="pre">TimeInput</span></tt><a class="headerlink" href="#timeinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.TimeInput">
<em class="property">class </em><tt class="descname">TimeInput</tt><a class="headerlink" href="#django.forms.TimeInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Time input as a simple text box: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='text'</span> <span class="pre">...&gt;</span></tt></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.TimeInput.format">
<tt class="descname">format</tt><a class="headerlink" href="#django.forms.TimeInput.format" title="Permalink to this definition">¶</a></dt>
<dd><p>The format in which this field's initial value will be displayed.</p>
</dd></dl>

<p>If no <tt class="docutils literal"><span class="pre">format</span></tt> argument is provided, the default format is the first
format found in <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/settings/#std:setting-TIME_INPUT_FORMATS"><tt class="xref std std-setting docutils literal"><span class="pre">TIME_INPUT_FORMATS</span></tt></a> and respects
<a class="reference internal" href="https://docs.djangoproject.com/en/dev/topics/i18n/formatting/#format-localization"><em>Format localization</em></a>.</p>
</dd></dl>

</div>
<div class="section" id="s-textarea">
<span id="textarea"></span><h3><tt class="docutils literal"><span class="pre">Textarea</span></tt><a class="headerlink" href="#textarea" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.Textarea">
<em class="property">class </em><tt class="descname">Textarea</tt><a class="headerlink" href="#django.forms.Textarea" title="Permalink to this definition">¶</a></dt>
<dd><p>Text area: <tt class="docutils literal"><span class="pre">&lt;textarea&gt;...&lt;/textarea&gt;</span></tt></p>
</dd></dl>

</div>
<div class="section" id="s-checkboxinput">
<span id="checkboxinput"></span><h3><tt class="docutils literal"><span class="pre">CheckboxInput</span></tt><a class="headerlink" href="#checkboxinput" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.CheckboxInput">
<em class="property">class </em><tt class="descname">CheckboxInput</tt><a class="headerlink" href="#django.forms.CheckboxInput" title="Permalink to this definition">¶</a></dt>
<dd><p>Checkbox: <tt class="docutils literal"><span class="pre">&lt;input</span> <span class="pre">type='checkbox'</span> <span class="pre">...&gt;</span></tt></p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.CheckboxInput.check_test">
<tt class="descname">check_test</tt><a class="headerlink" href="#django.forms.CheckboxInput.check_test" title="Permalink to this definition">¶</a></dt>
<dd><p>A callable that takes the value of the CheckBoxInput and returns
<tt class="xref docutils literal"><span class="pre">True</span></tt> if the checkbox should be checked for that value.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-select">
<span id="select"></span><h3><tt class="docutils literal"><span class="pre">Select</span></tt><a class="headerlink" href="#select" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.Select">
<em class="property">class </em><tt class="descname">Select</tt><a class="headerlink" href="#django.forms.Select" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget: <tt class="docutils literal"><span class="pre">&lt;select&gt;&lt;option</span> <span class="pre">...&gt;...&lt;/select&gt;</span></tt></p>
<dl class="attribute">
<dt id="django.forms.Select.choices">
<tt class="descname">choices</tt><a class="headerlink" href="#django.forms.Select.choices" title="Permalink to this definition">¶</a></dt>
<dd><p>This attribute is optional when the field does not have a
<tt class="xref py py-attr docutils literal"><span class="pre">choices</span></tt> attribute. If it does, it will override anything
you set here when the attribute is updated on the <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.Field" title="django.forms.Field"><tt class="xref py py-class docutils literal"><span class="pre">Field</span></tt></a>.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-nullbooleanselect">
<span id="nullbooleanselect"></span><h3><tt class="docutils literal"><span class="pre">NullBooleanSelect</span></tt><a class="headerlink" href="#nullbooleanselect" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.NullBooleanSelect">
<em class="property">class </em><tt class="descname">NullBooleanSelect</tt><a class="headerlink" href="#django.forms.NullBooleanSelect" title="Permalink to this definition">¶</a></dt>
<dd><p>Select widget with options 'Unknown', 'Yes' and 'No'</p>
</dd></dl>

</div>
<div class="section" id="s-selectmultiple">
<span id="selectmultiple"></span><h3><tt class="docutils literal"><span class="pre">SelectMultiple</span></tt><a class="headerlink" href="#selectmultiple" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.SelectMultiple">
<em class="property">class </em><tt class="descname">SelectMultiple</tt><a class="headerlink" href="#django.forms.SelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a>, but allows multiple selection:
<tt class="docutils literal"><span class="pre">&lt;select</span> <span class="pre">multiple='multiple'&gt;...&lt;/select&gt;</span></tt></p>
</dd></dl>

</div>
<div class="section" id="s-radioselect">
<span id="radioselect"></span><h3><tt class="docutils literal"><span class="pre">RadioSelect</span></tt><a class="headerlink" href="#radioselect" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.RadioSelect">
<em class="property">class </em><tt class="descname">RadioSelect</tt><a class="headerlink" href="#django.forms.RadioSelect" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a>, but rendered as a list of radio buttons within
<tt class="docutils literal"><span class="pre">&lt;li&gt;</span></tt> tags:</p>
<div class="highlight-html"><pre>&lt;ul&gt;
  &lt;li&gt;&lt;input type='radio' ...&gt;&lt;/li&gt;
  ...
&lt;/ul&gt;</pre>
</div>
<div class="versionadded">
<span class="title">New in Django Development version.</span> </div>
<p>For more granular control over the generated markup, you can loop over the
radio buttons in the template. Assuming a form <tt class="docutils literal"><span class="pre">myform</span></tt> with a field
<tt class="docutils literal"><span class="pre">beatles</span></tt> that uses a <tt class="docutils literal"><span class="pre">RadioSelect</span></tt> as its widget:</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">for</span> <span class="nv">radio</span> <span class="k">in</span> <span class="nv">myform.beatles</span> <span class="cp">%}</span>
<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"myradio"</span><span class="nt">&gt;</span>
    <span class="cp">{{</span> <span class="nv">radio</span> <span class="cp">}}</span>
<span class="nt">&lt;/div&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>This would generate the following HTML:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"myradio"</span><span class="nt">&gt;</span>
    <span class="nt">&lt;label&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"john"</span> <span class="nt">/&gt;</span> John<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"myradio"</span><span class="nt">&gt;</span>
    <span class="nt">&lt;label&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"paul"</span> <span class="nt">/&gt;</span> Paul<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"myradio"</span><span class="nt">&gt;</span>
    <span class="nt">&lt;label&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"george"</span> <span class="nt">/&gt;</span> George<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;/div&gt;</span>
<span class="nt">&lt;div</span> <span class="na">class=</span><span class="s">"myradio"</span><span class="nt">&gt;</span>
    <span class="nt">&lt;label&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"ringo"</span> <span class="nt">/&gt;</span> Ringo<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;/div&gt;</span>
</pre></div>
</div>
<p>That included the <tt class="docutils literal"><span class="pre">&lt;label&gt;</span></tt> tags. To get more granular, you can use each
radio button's <tt class="docutils literal"><span class="pre">tag</span></tt> and <tt class="docutils literal"><span class="pre">choice_label</span></tt> attributes. For example, this template...</p>
<div class="highlight-html+django"><div class="highlight"><pre><span class="cp">{%</span> <span class="k">for</span> <span class="nv">radio</span> <span class="k">in</span> <span class="nv">myform.beatles</span> <span class="cp">%}</span>
    <span class="nt">&lt;label&gt;</span>
        <span class="cp">{{</span> <span class="nv">radio.choice_label</span> <span class="cp">}}</span>
        <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"radio"</span><span class="nt">&gt;</span><span class="cp">{{</span> <span class="nv">radio.tag</span> <span class="cp">}}</span><span class="nt">&lt;/span&gt;</span>
    <span class="nt">&lt;/label&gt;</span>
<span class="cp">{%</span> <span class="k">endfor</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>...will result in the following HTML:</p>
<div class="highlight-html"><div class="highlight"><pre><span class="nt">&lt;label&gt;</span>
    John
    <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"radio"</span><span class="nt">&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"john"</span> <span class="nt">/&gt;&lt;/span&gt;</span>
<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;label&gt;</span>
    Paul
    <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"radio"</span><span class="nt">&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"paul"</span> <span class="nt">/&gt;&lt;/span&gt;</span>
<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;label&gt;</span>
    George
    <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"radio"</span><span class="nt">&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"george"</span> <span class="nt">/&gt;&lt;/span&gt;</span>
<span class="nt">&lt;/label&gt;</span>
<span class="nt">&lt;label&gt;</span>
    Ringo
    <span class="nt">&lt;span</span> <span class="na">class=</span><span class="s">"radio"</span><span class="nt">&gt;&lt;input</span> <span class="na">type=</span><span class="s">"radio"</span> <span class="na">name=</span><span class="s">"beatles"</span> <span class="na">value=</span><span class="s">"ringo"</span> <span class="nt">/&gt;&lt;/span&gt;</span>
<span class="nt">&lt;/label&gt;</span>
</pre></div>
</div>
<p>If you decide not to loop over the radio buttons -- e.g., if your template simply includes
<tt class="docutils literal"><span class="pre">{{</span> <span class="pre">myform.beatles</span> <span class="pre">}}</span></tt> -- they'll be output in a <tt class="docutils literal"><span class="pre">&lt;ul&gt;</span></tt> with <tt class="docutils literal"><span class="pre">&lt;li&gt;</span></tt> tags, as above.</p>
</dd></dl>

</div>
<div class="section" id="s-checkboxselectmultiple">
<span id="checkboxselectmultiple"></span><h3><tt class="docutils literal"><span class="pre">CheckboxSelectMultiple</span></tt><a class="headerlink" href="#checkboxselectmultiple" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.CheckboxSelectMultiple">
<em class="property">class </em><tt class="descname">CheckboxSelectMultiple</tt><a class="headerlink" href="#django.forms.CheckboxSelectMultiple" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.SelectMultiple" title="django.forms.SelectMultiple"><tt class="xref py py-class docutils literal"><span class="pre">SelectMultiple</span></tt></a>, but rendered as a list of check
buttons:</p>
<div class="highlight-html"><pre>&lt;ul&gt;
  &lt;li&gt;&lt;input type='checkbox' ...&gt;&lt;/li&gt;
  ...
&lt;/ul&gt;</pre>
</div>
</dd></dl>

</div>
<div class="section" id="s-multiwidget">
<span id="multiwidget"></span><h3><tt class="docutils literal"><span class="pre">MultiWidget</span></tt><a class="headerlink" href="#multiwidget" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.MultiWidget">
<em class="property">class </em><tt class="descname">MultiWidget</tt><a class="headerlink" href="#django.forms.MultiWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper around multiple other widgets. You'll probably want to use this
class with <a class="reference internal" href="https://docs.djangoproject.com/en/dev/ref/forms/fields/#django.forms.MultiValueField" title="django.forms.MultiValueField"><tt class="xref py py-class docutils literal"><span class="pre">MultiValueField</span></tt></a>.</p>
<p>Its <tt class="docutils literal"><span class="pre">render()</span></tt> method is different than other widgets', because it has to
figure out how to split a single value for display in multiple widgets.</p>
<p>Subclasses may implement <tt class="docutils literal"><span class="pre">format_output</span></tt>, which takes the list of
rendered widgets and returns a string of HTML that formats them any way
you'd like.</p>
<p>The <tt class="docutils literal"><span class="pre">value</span></tt> argument used when rendering can be one of two things:</p>
<ul class="simple">
<li>A <tt class="docutils literal"><span class="pre">list</span></tt>.</li>
<li>A single value (e.g., a string) that is the "compressed" representation
of a <tt class="docutils literal"><span class="pre">list</span></tt> of values.</li>
</ul>
<p>In the second case -- i.e., if the value is <em>not</em> a list -- <tt class="docutils literal"><span class="pre">render()</span></tt>
will first decompress the value into a <tt class="docutils literal"><span class="pre">list</span></tt> before rendering it. It
does so by calling the <tt class="docutils literal"><span class="pre">decompress()</span></tt> method, which
<a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><tt class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></tt></a>'s subclasses must implement. This method takes a
single "compressed" value and returns a <tt class="docutils literal"><span class="pre">list</span></tt>. An example of this is how
<a class="reference internal" href="#django.forms.SplitDateTimeWidget" title="django.forms.SplitDateTimeWidget"><tt class="xref py py-class docutils literal"><span class="pre">SplitDateTimeWidget</span></tt></a> turns a <tt class="xref py py-class docutils literal"><span class="pre">datetime</span></tt> value into a list
with date and time split into two seperate values:</p>
<div class="highlight-python"><div class="highlight"><pre><span class="k">class</span> <span class="nc">SplitDateTimeWidget</span><span class="p">(</span><span class="n">MultiWidget</span><span class="p">):</span>

    <span class="c"># ...</span>

    <span class="k">def</span> <span class="nf">decompress</span><span class="p">(</span><span class="bp">self</span><span class="p">,</span> <span class="n">value</span><span class="p">):</span>
        <span class="k">if</span> <span class="n">value</span><span class="p">:</span>
            <span class="k">return</span> <span class="p">[</span><span class="n">value</span><span class="o">.</span><span class="n">date</span><span class="p">(),</span> <span class="n">value</span><span class="o">.</span><span class="n">time</span><span class="p">()</span><span class="o">.</span><span class="n">replace</span><span class="p">(</span><span class="n">microsecond</span><span class="o">=</span><span class="mi">0</span><span class="p">)]</span>
        <span class="k">return</span> <span class="p">[</span><span class="bp">None</span><span class="p">,</span> <span class="bp">None</span><span class="p">]</span>
</pre></div>
</div>
<p>When <tt class="docutils literal"><span class="pre">render()</span></tt> executes its HTML rendering, each value in the list is
rendered with the corresponding widget -- the first value is rendered in
the first widget, the second value is rendered in the second widget, etc.</p>
<p><a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><tt class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></tt></a> has one required argument:</p>
<dl class="attribute">
<dt id="django.forms.MultiWidget.widgets">
<tt class="descname">widgets</tt><a class="headerlink" href="#django.forms.MultiWidget.widgets" title="Permalink to this definition">¶</a></dt>
<dd><p>An iterable containing the widgets needed.</p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-splitdatetimewidget">
<span id="splitdatetimewidget"></span><h3><tt class="docutils literal"><span class="pre">SplitDateTimeWidget</span></tt><a class="headerlink" href="#splitdatetimewidget" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.SplitDateTimeWidget">
<em class="property">class </em><tt class="descname">SplitDateTimeWidget</tt><a class="headerlink" href="#django.forms.SplitDateTimeWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper (using <a class="reference internal" href="#django.forms.MultiWidget" title="django.forms.MultiWidget"><tt class="xref py py-class docutils literal"><span class="pre">MultiWidget</span></tt></a>) around two widgets: <a class="reference internal" href="#django.forms.DateInput" title="django.forms.DateInput"><tt class="xref py py-class docutils literal"><span class="pre">DateInput</span></tt></a>
for the date, and <a class="reference internal" href="#django.forms.TimeInput" title="django.forms.TimeInput"><tt class="xref py py-class docutils literal"><span class="pre">TimeInput</span></tt></a> for the time.</p>
<p><tt class="docutils literal"><span class="pre">SplitDateTimeWidget</span></tt> has two optional attributes:</p>
<dl class="attribute">
<dt id="django.forms.SplitDateTimeWidget.date_format">
<tt class="descname">date_format</tt><a class="headerlink" href="#django.forms.SplitDateTimeWidget.date_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.DateInput.format" title="django.forms.DateInput.format"><tt class="xref py py-attr docutils literal"><span class="pre">DateInput.format</span></tt></a></p>
</dd></dl>

<dl class="attribute">
<dt id="django.forms.SplitDateTimeWidget.time_format">
<tt class="descname">time_format</tt><a class="headerlink" href="#django.forms.SplitDateTimeWidget.time_format" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.TimeInput.format" title="django.forms.TimeInput.format"><tt class="xref py py-attr docutils literal"><span class="pre">TimeInput.format</span></tt></a></p>
</dd></dl>

</dd></dl>

</div>
<div class="section" id="s-splithiddendatetimewidget">
<span id="splithiddendatetimewidget"></span><h3><tt class="docutils literal"><span class="pre">SplitHiddenDateTimeWidget</span></tt><a class="headerlink" href="#splithiddendatetimewidget" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.SplitHiddenDateTimeWidget">
<em class="property">class </em><tt class="descname">SplitHiddenDateTimeWidget</tt><a class="headerlink" href="#django.forms.SplitHiddenDateTimeWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Similar to <a class="reference internal" href="#django.forms.SplitDateTimeWidget" title="django.forms.SplitDateTimeWidget"><tt class="xref py py-class docutils literal"><span class="pre">SplitDateTimeWidget</span></tt></a>, but uses <a class="reference internal" href="#django.forms.HiddenInput" title="django.forms.HiddenInput"><tt class="xref py py-class docutils literal"><span class="pre">HiddenInput</span></tt></a> for
both date and time.</p>
</dd></dl>

</div>
<div class="section" id="s-selectdatewidget">
<span id="selectdatewidget"></span><h3><tt class="docutils literal"><span class="pre">SelectDateWidget</span></tt><a class="headerlink" href="#selectdatewidget" title="Permalink to this headline">¶</a></h3>
<dl class="class">
<dt id="django.forms.extras.widgets.SelectDateWidget">
<em class="property">class </em><tt class="descname">SelectDateWidget</tt><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget" title="Permalink to this definition">¶</a></dt>
<dd><p>Wrapper around three <a class="reference internal" href="#django.forms.Select" title="django.forms.Select"><tt class="xref py py-class docutils literal"><span class="pre">Select</span></tt></a> widgets: one each for
month, day, and year. Note that this widget lives in a separate file from
the standard widgets.</p>
<p>Takes one optional argument:</p>
<dl class="attribute">
<dt id="django.forms.extras.widgets.SelectDateWidget.years">
<tt class="descname">years</tt><a class="headerlink" href="#django.forms.extras.widgets.SelectDateWidget.years" title="Permalink to this definition">¶</a></dt>
<dd><p>An optional list/tuple of years to use in the "year" select box.
The default is a list containing the current year and the next 9 years.</p>
</dd></dl>

</dd></dl>

</div>
</div>
</div>



<div id="content-secondary">
  <h2 id="comments">Questions/Feedback</h2>
  <p>Having trouble? We'd like to help!</p>
  <ul>
    <li>
      Try the <a href="https://docs.djangoproject.com/en/dev/faq/">FAQ</a>
      — it's got answers to many common questions.
    </li>
    <li>
      Search for information in the <a href="http://groups.google.com/group/django-users/">archives of the
      django-users mailing list</a>, or <a href="http://groups.google.com/group/django-users/">post a question</a>.
    </li>
    <li>
      Ask a question in the <a href="irc://irc.freenode.net/">#django IRC
      channel</a>, or search the <a href="http://django-irc-logs.com/">IRC
      logs</a> to see if it has been asked before.
    </li>
    <li>
      If you notice errors with this documentation, please <a href="https://code.djangoproject.com/newticket?component=Documentation">
      open a ticket</a> and let us know! Please only use the ticket tracker for
      criticisms and improvements on the docs. For tech support, use the
      resources above.
    </li>
  </ul>
</div>

		</div>
		<!-- END #content-main -->
		<div id="content-related" class="sidebar">
		
  
    <h2>Search</h2>
    
    <form action="/search/" id="sidebar_search" class="search">
  <div>
    <p>
      <input name="q" id="id_sidebar_search_q" type="search">
    </p>
    <p>
      <label for="id_sidebar_search_release">Version:</label>
      <select name="release" id="id_sidebar_search_release">
<option value="2">Django 1.0</option>
<option value="3">Django 1.1</option>
<option value="4">Django 1.2</option>
<option value="5" selected="selected">Django 1.3</option>
<option value="1">Development trunk</option>
</select>
    </p>
    <p>
      <input class="submit" value="Search" type="submit">
    </p>
  </div>
</form>
  

  
    <h2>Contents</h2>
    
      <ul>
<li><a class="reference internal" href="#">Widgets</a><ul>
<li><a class="reference internal" href="#specifying-widgets">Specifying widgets</a></li>
<li><a class="reference internal" href="#setting-arguments-for-widgets">Setting arguments for widgets</a></li>
<li><a class="reference internal" href="#widgets-inheriting-from-the-select-widget">Widgets inheriting from the Select widget</a></li>
<li><a class="reference internal" href="#customizing-widget-instances">Customizing widget instances</a></li>
<li><a class="reference internal" href="#built-in-widgets">Built-in widgets</a><ul>
<li><a class="reference internal" href="#widget"><tt class="docutils literal"><span class="pre">Widget</span></tt></a></li>
<li><a class="reference internal" href="#textinput"><tt class="docutils literal"><span class="pre">TextInput</span></tt></a></li>
<li><a class="reference internal" href="#passwordinput"><tt class="docutils literal"><span class="pre">PasswordInput</span></tt></a></li>
<li><a class="reference internal" href="#hiddeninput"><tt class="docutils literal"><span class="pre">HiddenInput</span></tt></a></li>
<li><a class="reference internal" href="#multiplehiddeninput"><tt class="docutils literal"><span class="pre">MultipleHiddenInput</span></tt></a></li>
<li><a class="reference internal" href="#fileinput"><tt class="docutils literal"><span class="pre">FileInput</span></tt></a></li>
<li><a class="reference internal" href="#clearablefileinput"><tt class="docutils literal"><span class="pre">ClearableFileInput</span></tt></a></li>
<li><a class="reference internal" href="#dateinput"><tt class="docutils literal"><span class="pre">DateInput</span></tt></a></li>
<li><a class="reference internal" href="#datetimeinput"><tt class="docutils literal"><span class="pre">DateTimeInput</span></tt></a></li>
<li><a class="reference internal" href="#timeinput"><tt class="docutils literal"><span class="pre">TimeInput</span></tt></a></li>
<li><a class="reference internal" href="#textarea"><tt class="docutils literal"><span class="pre">Textarea</span></tt></a></li>
<li><a class="reference internal" href="#checkboxinput"><tt class="docutils literal"><span class="pre">CheckboxInput</span></tt></a></li>
<li><a class="reference internal" href="#select"><tt class="docutils literal"><span class="pre">Select</span></tt></a></li>
<li><a class="reference internal" href="#nullbooleanselect"><tt class="docutils literal"><span class="pre">NullBooleanSelect</span></tt></a></li>
<li><a class="reference internal" href="#selectmultiple"><tt class="docutils literal"><span class="pre">SelectMultiple</span></tt></a></li>
<li><a class="reference internal" href="#radioselect"><tt class="docutils literal"><span class="pre">RadioSelect</span></tt></a></li>
<li><a class="reference internal" href="#checkboxselectmultiple"><tt class="docutils literal"><span class="pre">CheckboxSelectMultiple</span></tt></a></li>
<li><a class="reference internal" href="#multiwidget"><tt class="docutils literal"><span class="pre">MultiWidget</span></tt></a></li>
<li><a class="reference internal" href="#splitdatetimewidget"><tt class="docutils literal"><span class="pre">SplitDateTimeWidget</span></tt></a></li>
<li><a class="reference internal" href="#splithiddendatetimewidget"><tt class="docutils literal"><span class="pre">SplitHiddenDateTimeWidget</span></tt></a></li>
<li><a class="reference internal" href="#selectdatewidget"><tt class="docutils literal"><span class="pre">SelectDateWidget</span></tt></a></li>
</ul>
</li>
</ul>
</li>
</ul>

    
  
  
    <h2>Browse</h2>
    <ul>
      
        
          <li>Prev: <a href="https://docs.djangoproject.com/en/dev/ref/forms/fields/">Form fields</a></li>
        
        
          <li>Next: <a href="https://docs.djangoproject.com/en/dev/ref/forms/validation/">Form and field validation</a></li>
        
        <li><a href="https://docs.djangoproject.com/en/dev/contents/">Table of contents</a></li>
        
          <li><a href="https://docs.djangoproject.com/en/dev/genindex/">General Index</a></li>
        
          <li><a href="https://docs.djangoproject.com/en/dev/py-modindex/">Python Module Index</a></li>
        
      
    </ul>
  

  
    <h2>You are here:</h2>
    <ul>
      
        <li>
          <a href="https://docs.djangoproject.com/en/dev/">Django dev documentation</a>
          
            <ul><li><a href="https://docs.djangoproject.com/en/dev/ref/">API Reference</a>
          
            <ul><li><a href="https://docs.djangoproject.com/en/dev/ref/forms/">Forms</a>
          
          <ul><li>Widgets</li></ul>
          </li></ul></li></ul>
        </li>
      
    </ul>

    
      <h2>Download:</h2>
      <p>
      
        Offline (development version):
        <a href="https://www.djangoproject.com/m/docs/django-docs-dev-en.zip">HTML</a> |
        <a href="http://media.readthedocs.org/pdf/django/latest/django.pdf">PDF</a> |
        <a href="http://media.readthedocs.org/epub/django/latest/django.epub">ePub</a>
      
      <br>
      <span class="quiet">Provided by <a href="http://readthedocs.org/">Read the Docs</a>.
      </span></p>
    
  

		</div>
		<!-- END #content-related -->

    </div>
    <!-- END #content -->
    <div id="footer">
      <p>© 2005-2012 <a href="https://www.djangoproject.com/foundation/">Django Software Foundation</a> unless otherwise noted. Django is a registered trademark of the Django Software Foundation.
      <a href="http://mediatemple.net/">Linux Web hosting</a> graciously provided by Media Temple.
      </p>
    </div>
    <!-- END #footer -->
  </div>
  <!-- END #container -->
  


</body></html>